---
title: 编程式 Astro API（实验性）
i18nReady: true
---
import Since from '~/components/Since.astro';

如果你在运行 Astro 时需要进行更多的控制，可以使用 `"astro"` 包导出的 API 以编程方式运行 CLI 命令。

这些 API 是实验性的，其 API 签名可能会更改。任何更新都会在 [Astro changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) 中提及，下面的信息将始终显示最新的信息。

## `AstroInlineConfig`

`AstroInlineConfig` 类型由以下的所有命令 API 使用。它继承自用户的 [Astro 配置](/zh-cn/reference/configuration-reference/) 类型：

```ts
interface AstroInlineConfig extends AstroUserConfig {
	configFile?: string | false;
	mode?: string;
	logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}
```

### `configFile`

<p>

**类型：** `string | false`<br />
**默认值：** `undefined`
</p>

Astro 配置文件的自定义路径。

如果这个值为 undefined（默认值） 或 unset，那么 Astro 将尝试搜索一个相对 `root` 目录的 `astro.config.(js,mjs,ts,mts)` 文件，如果找到的话，则加载配置文件。

如果设置了相对路径，它将根据 `root` 选项进行解析。

设置为 `false` 将禁用加载任何配置文件。

当与加载的用户配置并行时，此对象中传递的内联配置将具有最高优先级。

### `mode`

<p>

**类型：** `string`<br />
**默认值：** 运行 `astro dev` 时为 `"development"`，运行 `astro build` 时为 `"production"`<br />
<Since v="5.0.0" />
</p>

开发或构建网站时使用的模式（例如，`"production"`，`"testing"`）。

当运行 `astro build` 或 `astro dev` 命令时，这个值会使用 [`--mode` 标志](/zh-cn/reference/cli-reference/#--mode-string) 传递给 Vite，以确定 `import.meta.env.MODE` 的值。这也决定了加载哪些 `.env` 文件，从而决定了 `astro：env` 的值。有关更多详细信息，请参阅 [环境变量](/zh-cn/guides/environment-variables/) 页面。

要输出基于开发的构建，你可以使用 [`--devOutput` 标志](/zh-cn/reference/cli-reference/#--devoutput) 运行 `astro build`。

### `logLevel`

<p>

**类型：** `"debug" | "info" | "warn" | "error" | "silent"`<br />
**默认值：** `"info"`
</p>

用于过滤 Astro 所记录的消息的日志记录级别。

- `"debug"`：记录所有内容，包括嘈杂的调试诊断。
- `"info"`：记录信息性消息、警告和错误。
- `"warn"`：记录警告和错误。
- `"error"`：仅记录错误。
- `"silent"`：无日志记录。

## `dev()`

<p>

**类型：** `(inlineConfig: AstroInlineConfig) => Promise<DevServer>`
</p>

与 [`astro dev`](/zh-cn/reference/cli-reference/#astro-dev) 相似，用于运行 Astro 的开发服务器。

```js
import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// 如需停止服务器：
await devServer.stop();
```

### `DevServer`

```ts
export interface DevServer {
	address: AddressInfo;
	handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
	watcher: vite.FSWatcher;
	stop(): Promise<void>;
}
```

#### `address`

<p>

**类型：** `AddressInfo`
</p>

开发服务器正在监听的地址。

此属性包含 Node 的 [`net.Server#address()` 方法]（https://nodejs.org/api/net.html#serveraddress）。

#### `handle()`

<p>

**类型：** `(req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void`
</p>

原始 Node HTTP 请求的句柄。你可以用 [`http.IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) 和 [`http.ServerResponse`](https://nodejs.org/api/http.html#class-httpserverresponse) 来调用 `handle()`，而不是通过网络发送请求。

#### `watcher`

<p>

**类型：** `vite.FSWatcher`
</p>

[Vite 的开发服务器](https://cn.vite.dev/guide/api-javascript#vitedevserver) 暴露的 [Chokidar 文件监视器](https://github.com/paulmillr/chokidar#getting-started)。

#### `stop()`

<p>

**类型：** `Promise<void>`
</p>

停止开发服务器。这将关闭所有空闲连接并停止监听新连接。

返回一个 `Promise`，该 Promise 在完成所有待处理请求并关闭所有空闲连接后结束。

## `build()`

<p>

**类型：** `(inlineConfig: AstroInlineConfig, options?: BuildOptions) => Promise<void>`
</p>

与 [`astro build`](/zh-cn/reference/cli-reference/#astro-build) 相似，用于构建你的站点以进行部署。

```js
import { build } from "astro";

await build({
  root: "./my-project",
});
```

### `BuildOptions`

```ts
export interface BuildOptions {
	devOutput?: boolean;
	teardownCompiler?: boolean;
}
```

#### `devOutput`

<p>

**类型：** `boolean`<br />
**默认值：** `false`
<Since v="5.4.0" />
</p>

输出一个基于开发的构建，与在 `astro dev` 中转换的代码相似。这对于测试仅构建时出现的问题非常有用，同时包含附加的调试信息。

#### `teardownCompiler`

<p>

**类型：** `boolean`<br />
**默认值：** `true`<br />
<Since v="5.4.0" />
</p>

在构建完成后销毁编译器的 WASM 实例。这可以在单次构建时提升性能，但在连续多次构建时可能导致性能下降。

在同一次执行中构建多个项目时（例如测试期间），禁用这个选项可以显著提升性能并降低峰值内存占用，但代价是持续内存占用会升高。

## `preview()`

<p>

**类型：** `(inlineConfig: AstroInlineConfig) => Promise<PreviewServer>`
</p>

与 [`astro preview`](/zh-cn/reference/cli-reference/#astro-preview) 相似，用于启动一个本地服务器来提供你的构建输出。

如果未在配置中设置适配器，则预览服务器将仅服务于构建中静态的文件。
如果在配置中设置了适配器，则预览服务器将由适配器提供。适配器不需要提供预览服务器，因此该功能可能不可用，具体取决于你选择的适配器。

```js
import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// 如需停止服务器：
await previewServer.stop();
```

### `PreviewServer`

```ts
export interface PreviewServer {
	host?: string;
	port: number;
	closed(): Promise<void>;
	stop(): Promise<void>;
}
```

#### `host`

<p>

**类型：** `string`
</p>

服务器所监听连接的 host。

允许适配器不设置此字段。`host` 的值通过特殊方式实现。

#### `port`

<p>

**类型：** `number`
</p>

服务器所监听连接的端口。

#### `stop()`

<p>

**类型：** `Promise<void>`
</p>

要求预览服务器关闭、停止接受请求并关闭空闲连接。

返回的 `Promise` 在发送关闭请求后解析。这并不意味着服务器已经关闭。如果需要确保服务器已完全关闭，请使用 [`closed()`](#closed) 方法。

#### `closed()`

<p>

**类型：** `Promise<void>`
</p>

返回一个 `Promise`，该 Promise 将在服务器关闭后结束，如果服务器上发生错误，则拒绝该 Promise。

## `sync()`

<p>

**类型：** `(inlineConfig: AstroInlineConfig) => Promise<void>`
</p>

与 [`astro sync`](/zh-cn/reference/cli-reference/#astro-sync) 相似，用于为所有的 Astro 模块生成 TypeScript 类型。

```js
import { sync } from "astro";

await sync({
  root: "./my-project",
});
```

## `mergeConfig()`

<p>

**类型：** `<T extends AstroConfig | AstroInlineConfig>(config: T, overrides: DeepPartial<T>) => T`
<Since v="5.4.0" />
</p>

从 `astro/config` 导入，用于在现有有效的 Astro 配置基础上合并部分配置。

`mergeConfig()` 接受一个完整的 Astro 配置对象和一个部分配置（任意有效的 Astro 配置选项的集合），返回合并后的有效 Astro 配置。合并规则如下：

- 数组会被连接（包括集成和 remark 插件）。
- 对象会递归合并。
- Vite 选项使用 [Vite 自身的 `mergeConfig` 函数](https://cn.vite.dev/guide/api-javascript#mergeconfig) 进行合并，默认启用 `isRoot` 标志。
- 可以作为函数提供的选项会被包装成新函数，这些新函数递归合并两个配置的返回值，遵循相同的规则。
- 其他所有选项会覆盖原有配置。

```ts
import { mergeConfig } from "astro/config";

mergeConfig(
  {
    output: 'static',
    site: 'https://example.com',
    integrations: [partytown()],
    server: ({command}) => ({
      port: command === 'dev' ? 4321 : 1234,
    }),
	  build: {
		  client: './custom-client',
	  },
  },
  {
    output: 'server',
    base: '/astro',
    integrations: [mdx()],
    server: ({command}) => ({
      host: command === 'dev' ? 'localhost' : 'site.localhost',
    }),
	  build: {
		  server: './custom-server',
	  },
  }
);

// 合并后的结果等价于：
{
  output: 'server',
  site: 'https://example.com',
  base: '/astro',
  integrations: [partytown(), mdx()],
  server: ({command}) => ({
    port: command === 'dev' ? 4321 : 1234,
    host: command === 'dev' ? 'localhost' : 'site.localhost',
  }),
	build: {
		client: './custom-client',
		server: './custom-server',
	},
}
```

## `validateConfig()`

<p>

**类型：** `(userConfig: any, root: string, cmd: string): Promise<AstroConfig>`
<Since v="5.4.0" />
</p>

从 `astro/config` 导入，用于验证一个对象，就好像该对象是从 `astro.config.mjs` 导出并由 Astro 导入的一样。


接收以下参数：
- 待验证的配置
- 项目根目录
- 正在执行的 Astro 命令（`build`, `dev`, `sync` 等）

返回的 Promise 会解析为验证后的配置，包含适用于给定 Astro 命令的所有默认值。

```ts
import { validateConfig } from "astro/config";

const config = await validateConfig({
  integrations: [partytown()],
}, "./my-project", "build");

// 已应用默认值
await rm(config.outDir, { recursive: true, force: true });
```
